This looks great. I appreciate that you're versioning packages in place to avoid breaking existing beta users when a package becomes stable, and that you've found a balance between a generic cross-language versioning scheme with Go's more stringent requirements.

One request: contrib isn't mentioned here, but it would be good to clarify versioning for contrib packages as well, including the requirement that contrib packages must be kept up to date with the latest release of core.

This looks great. I appreciate that you're versioning packages in place to avoid breaking existing beta users when a package becomes stable, and that you've found a balance between a generic cross-language versioning scheme with Go's more stringent requirements.

One request: contrib isn't mentioned here, but it would be good to clarify versioning for contrib packages as well, including the requirement that contrib packages must be kept up to date with the latest release of core.

@tedsuo I added a section for the contrib project. PTAL

@MrAlias Excellent writeup. +1 on the distinction between stable and other versions.
A couple of questions -

1. How does backward compatibility support influence version numbering?
2. You mention "Users are provided a codebase of value that is stable and secure." - Can you add more clarity about if/how versioning is affected by security CVE patches and backward compat.

@rakyll would love to get your comments.

1. How does backward compatibility support influence version numbering?

Backwards compatibility is guaranteed by the major version number as specified by semver 2.0

Major version X (X.y.z | X > 0) MUST be incremented if any backwards incompatible changes are introduced to the public API.

This means modules released with the same major version number will remain backwards compatible.

2. You mention "Users are provided a codebase of value that is stable and secure." - Can you add more clarity about if/how versioning is affected by security CVE patches and backward compat.

Any type of patching of a bug (e.g. security, performance, correctness) will result in a patch version increment as specified by semver 2.0

Patch version Z (x.y.Z | x > 0) MUST be incremented if only backwards compatible bug fixes are introduced. A bug fix is defined as an internal change that fixes incorrect behavior.

@MrAlias This is really, really, really excellent. 💯